.. _辅助工具使用教程:
************************************
辅助工具使用教程
************************************



.. _环境部署:

==============================================================================
环境部署
==============================================================================

------------------------------------------------------------------------------------------------------------------------------------------------------------------

依赖环境: **Python3.6及以上**
 
- 依赖库安装：
 (1) **Pymatgen库** ：使用 ``pip install pymatgen`` 安装；
 (2) **Statsmodels库** ：使用 ``pip install statsmodels`` 安装；
 (3) **Dspawpy库** ：使用 ``pip install -i https://test.pypi.org/simple/ dspawpy==0.1.3`` 安装；

.. _ 能带数据处理:

==============================================================================
能带数据处理
==============================================================================

------------------------------------------------------------------------------------------------------------------------------------------------------------------

以不开自旋时的MoS2体系的 ``band.json`` 为例子：

（1） **普通能带处理** ：

创建 :guilabel:`bandplot.py` 文件，具体代码如下：

.. code-block:: python

    from pymatgen.electronic_structure.plotter import BSPlotter
    #导入dspawpy 读取band.json 模块
    from dspawpy.io import get_band_data

    #读取band.json, 参数band.json 路径
    band_data = get_band_data("./band.json")

    bsp = BSPlotter(bs=band_data)
    # 绘制Band图，返回matplotlib.pyplot
    plt = bsp.get_plot()
    # 保存png图片
    plt.savefig("bandplot.png",img_format="png")
    plt.show()

.. admonition:: 知识点：

    1. `Pymatgen中主要用到 electronic_structure.plotter 模块，基本上该模块下的80%的功能都能使用；`
    2. `dspawpy.io 模块为 DS-PAW 的接口模块；`
    3. `使用 get_band_data 函数可以将 DS-PAW 计算得到的 band.json 文件转化为 pymatgen 支持的格式；`
    4. `使用 BSPlotter 模块获取到 DS-PAW 计算的 band.json 的数据；`
    5. `使用 BSPlotter 模块中 get_plot 函数绘制能带图；`
    6. `使用 savefig 函数可以将能带图以不同格式保存；`
    7. `使用 show 函数能够直接显示能带图，如果用户的机器上不支持图形界面，可以用#注释 show函数；`

执行代码可以得到以下能带图：

.. figure:: images/4-1.png

（2） **将能带投影到每一种元素然后分别作图，通过线条的粗细来表示该元素对该轨道的贡献** ：

创建 :guilabel:`bandplot_elt_projected.py` 文件，具体代码如下：

.. code-block:: python

    from pymatgen.electronic_structure.plotter import BSPlotterProjected
    from dspawpy.io import get_band_data

    band_data = get_band_data("./band.json")

    # 构建投影band数据实例
    bsp = BSPlotterProjected(bs=band_data)
    # 绘制按元素投影图片,返回matplotlib.pyplot
    plt = bsp.get_elt_projected_plots()
    plt.savefig("bandplot_elt_projected.png",img_format="png")
    plt.show()

.. admonition:: 知识点：

    1.  `用户如果需要绘制能带投影的数据，此时需要使用 BSPlotterProjected模块；`
    2.  `使用 BSPlotterProjected模块中 get_elt_projected_plots 函数能够绘制每种元素对轨道贡献的能带图；`

执行代码可以得到以下能带图：

.. figure:: images/4-2.png

（3） **将能带投影到每一种元素然后分别作图，通过不同的颜色来表示该元素对该轨道的贡献：**

创建 :guilabel:`bandplot_elt_projected_color.py` 文件，具体代码如下：

.. code-block:: python

    from pymatgen.electronic_structure.plotter import BSPlotterProjected
    from dspawpy.io import get_band_data

    band_data = get_band_data("./data/band.json")

    bsp = BSPlotterProjected(bs=band_data)
    # 绘制投影到元素band图片,返回matplotlib.pyplot({'Mo':['d'],'S':['s']})
    plt = bsp.get_elt_projected_plots_color()
    plt.savefig("bandplot_elt_projected_color.png",img_format="png")
    plt.show()

.. admonition:: 知识点：

    `使用 BSPlotterProjected模块中 bandplot_elt_projected_color 函数能够绘制每种元素对轨道贡献的能带图，用红绿蓝三原色来表示 spd轨道；`

执行代码可以得到以下能带图：

.. figure:: images/4-3.png

（4） **能带投影到不同元素的不同轨道（L）：**

创建 :guilabel:`bandplot_projected.py` 文件，具体代码如下：

.. code-block:: python

    from pymatgen.electronic_structure.plotter import BSPlotterProjected
    from dspawpy.io import get_band_data

    band_data = get_band_data("./data/band.json")

    bsp = BSPlotterProjected(bs=band_data)

    # 绘制投影到元素某些轨道band，返回matplotlib.pyplot
    plt = bsp.get_projected_plots_dots({'Mo':['d'],'S':['s']})
    plt.savefig("bandplot_projected.png",img_format="png")
    plt.show()

.. admonition:: 知识点：

   1. `使用 BSPlotterProjected模块中 get_projected_plots_dots可以让用户来自定义需要绘制的某种元素某种轨道(L)的能带图；`
   2. `例如 get_projected_plots_dots ({'Mo':['d'],'S':['s']})就是绘制Mo的d轨道和S的s轨道；`

执行代码可以得到以下能带图：

.. figure:: images/4-4.png

（5） **将能带投影到不同原子的不同轨道(M)：**

创建 :guilabel:`bandplot_plots_dots_patom_pmorb.py` 文件，具体代码如下：

.. code-block:: python

    from pymatgen.electronic_structure.plotter import BSPlotterProjected
    from dspawpy.io import get_band_data

    band_data = get_band_data("./band.json")

    bsp = BSPlotterProjected(bs=band_data)
    # 绘制投影到原子部分轨道band图片,返回matplotlib.pyplot
    plt = bsp.get_projected_plots_dots_patom_pmorb(dictio={'Mo':['px','py','pz']},
                                                   dictpa={Mo':[1]})

    plt.savefig("bandplot_projected_plots_dots_patom_pmorb.png",img_format="png")
    plt.show()

.. admonition:: 知识点：

    1.  `使用 BSPlotterProjected模块中 get_projected_plots_dots_patom_pmorb 的自由度更高，可以让用户来自定义需要绘制的某种原子某种轨道 (M) 的能带图；`
    2.  `dictpa指定原子，dictio 指定该原子的轨道；`
    3.  `get_projected_plots_dots_patom_pmorb函数中还可以使用 sum_atoms 功能将多个原子的贡献相加，该功能用户可以自行根据使用方法进行尝试；`

**注意：get_projected_plots_dots_patom_pmorb函数中序号是从1开始的；**

执行代码可以得到以下能带图：

.. figure:: images/4-5.png

.. _ 态密度数据处理:

==============================================================================
态密度数据处理
==============================================================================

------------------------------------------------------------------------------------------------------------------------------------------------------------------

以应用教程中的反铁磁NiO体系的 ``dos.json`` 为例子：

（1） **总的态密度** ：

创建 :guilabel:`dosplot_total.py` 文件，具体代码如下：

.. code-block:: python

    from pymatgen.electronic_structure.plotter import DosPlotter
    from dspawpy.io import get_dos_data


    dos_data = get_dos_data("dos.json")
    dos_plotter = DosPlotter(stack=False,zero_at_efermi=True)

    # 添加total dos
    dos_plotter.add_dos('total dos',dos=dos_data)

    # 返回matplotlib.py
    plt = dos_plotter.get_plot()
    plt.savefig("dos_total.png",img_format="png")
    plt.show()

.. admonition:: 知识点：

    1.  `使用 get_dos_data 函数可以将DS-PAW计算得到的 dos.json 文件转化为 pymatgen 支持的格式；`
    2.  `使用 DosPlotter模块获取到DS-PAW计算的 dos.sjon 的数据；`
    3.  `DosPlotter函数可以传递参数：stack参数表示画态密度是否加阴影， zero_at_efermi 表示是否在态密度图中进行将费米能量置零，这里设置 stack=False , zero_at_efermi=False ；`
    4.  `使用 DosPlotter 模块中 add_dos 获取态密度的数据；`
    5.  `DosPlotter模块中 et_plot函数 绘制态密度图；`

执行代码可以得到以下态密度图：

.. figure:: images/4-6.png

（2） **将态密度投影到不同的轨道上(L)：**

创建 :guilabel:`dosplot_spd.py` 文件，具体代码如下：

.. code-block:: python

    from pymatgen.electronic_structure.plotter import DosPlotter
    from dspawpy.io import get_dos_data


    dos_data = get_dos_data("dos.json")
    dos_plotter = DosPlotter(stack=False,zero_at_efermi=True)
    # 添加spd轨道dos数据
    dos_plotter.add_dos_dict(dos_data.get_spd_dos())

    # 返回matplotlib.pyplot
    plt = dos_plotter.get_plot()
    plt.savefig("dos_spd.png",img_format="png")
    plt.show()

.. admonition:: 知识点：

    1. `使用 DosPlotter模块中 add_dos_dict 函数 获取投影态密度的数据，之后使用 get_spd_dos 将投影信息按照 spd 轨道投影输出；`

执行代码可以得到以下态密度图：

.. figure:: images/4-7.png

（3） **将态密度投影到不同的元素上** ：

创建 :guilabel:`dosplot_element.py` 文件，具体代码如下：

.. code-block:: python

    # 导入pymatgen DosPlotter模块
    from pymatgen.electronic_structure.plotter import DosPlotter
    # 导入读取DS-PAW dos.json数据模块
    from dspawpy.io import get_dos_data


    dos_data = get_dos_data("dos.json")
    dos_plotter = DosPlotter(stack=False,zero_at_efermi=True)

    #按元素添加dos
    dos_plotter.add_dos_dict(dos_data.get_element_dos())

    #返回matplotlib.pyplot
    plt = dos_plotter.get_plot()
    plt.savefig("dos_element.png",img_format="png")
    plt.show()

.. admonition:: 知识点：

    1. `使用 DosPlotter模块中 add_dos_dict 函数 获取投影态密度的数据，之后使用 get_element_dos 将投影信息按照不同元素投影输出；`


执行代码可以得到以下态密度图：

.. figure:: images/4-8.png

（4） **将态密度投影到不同的元素的不同轨道(M)上：**

创建 :guilabel:`dosplot_element_orbital.py` 文件，具体代码如下：

.. code-block:: python

    from pymatgen.electronic_structure.plotter import DosPlotter
    from pymatgen.electronic_structure.core import Orbital
    from dspawpy.io import get_dos_data


    dos_data = get_dos_data("dos.json")
    dos_plotter = DosPlotter(stack=False,zero_at_efermi=False)
    dos_plotter.add_dos("Ni dxy",dos_data.get_site_orbital_dos(dos_data.structure[0],Orbital(4)))
    #dos_plotter.save_plot("dos_element_orbital.png",img_format="png")
    dos_plotter.show()

.. admonition:: 知识点：

    1. `使用 get_site_orbital_dos函数 提取dos数据中特定原子，特定轨道的贡献，这是获取第2个原子的第5个轨道的态密度 dos_data.structure[0],Orbital(4)` ；
    2. `之后使用 DosPlotter模块中 add_dos函数 进行画图；`

**注意：get_site_orbital_dos函数中序号是从0开始的；**

执行代码可以得到以下态密度图：

.. figure:: images/4-9.png

（5） 将态密度投影到不同的原子的t2g轨道和eg轨道上：

创建 :guilabel:`dosplot_t2g_eg.py` 文件，具体代码如下：

.. code-block:: python

    from pymatgen.electronic_structure.plotter import DosPlotter
    from dspawpy.io import get_dos_data

    dos_data = get_dos_data("dos.json")
    dos_plotter = DosPlotter(stack=False,zero_at_efermi=False)
    # 添加t2g eg dos
    dos_plotter.add_dos_dict(dos_data.get_site_t2g_eg_resolved_dos(dos_data.structure[0]))

    # 返回matplotlib.py
    plt = dos_plotter.get_plot()
    plt.savefig("dos_t2g_eg.png",img_format="png")
    plt.show()

.. admonition:: 知识点：

    1. `使用 get_site_t2g_eg_resolved_dos函数 提取dos数据中特定原子的 t2g和 eg轨道的贡献，这是获取第1个原子的t2g和eg轨道的贡献；`
    2. `之后使用 DosPlotter 模块中 add_dos_dict函数 进行画图；`

执行代码可以得到以下态密度图：

.. figure:: images/4-10.png

.. _ 能带和态密度共同显示:

==============================================================================
能带和态密度共同显示
==============================================================================

------------------------------------------------------------------------------------------------------------------------------------------------------------------

以应用教程中Si体系的 ``band.json`` 和 ``dos.json`` 为例子：

（1） **将能带和态密度显示在一张图上：**

创建 :guilabel:`banddosplot.py` 文件，具体代码如下：

.. code-block:: python

    # 导入pymatgen BSDOSPlotter 画图模块
    from pymatgen.electronic_structure.plotter import BSDOSPlotter
    # 导入dspawpy 读取DS-PAW band.json,dos.json模块
    from dspawpy.io import get_band_data,get_dos_data

    # 读取dos.json, 参数dos.json文件路径
    dos_data = get_dos_data("./data/dos.json")
    # 读取band.json, 参数band.json文件路径
    band_data = get_band_data("./data/band.json")

    bdp = BSDOSPlotter()

    # 绘制BandDos图，返回matplotlib.pyplot
    plt = bdp.get_plot(bs=band_data,dos=dos_data)

    # 保存png图片
    plt.savefig("banddos.png",img_format="png")
    # 显示图片
    plt.show()

.. admonition:: 知识点：

    1. `首先使用 dspawpy.io 中的 get_band_data 和 get_dos_data 模块获取 band.json 和 dos.json 的数据；`
    2. `之后使用 BSDOSPlotter模块中的 get_plots函数 直接进行画图；`
    3. `如果需要将投影能带和投影态密度画在一起，可以参考前面单独画图的代码。`

执行代码可以得到以下能带态密度图：

.. figure:: images/4-11.png

.. _ 势函数数据处理:

==============================================================================
势函数数据处理
==============================================================================

------------------------------------------------------------------------------------------------------------------------------------------------------------------

以Si的slab模型的 ``potential.json`` 为例：

（1） **势函数转化为VESTA能够支持的三维显示格式**：

创建 :guilabel:`trans_VESTA.py` 文件，具体代码如下：

.. code-block:: python

    import json
    # 导入将DS-PAW 输出转到VESTA支持的绘图格式
    from dspawpy.io import write_VESTA_format

    # 读取potential.json 数据
    with open("./data/potential.json","r") as file:
        potential= json.load(file)

    # 转换格式,参数: AtomInfo
    # [data,...] 转换的数据,支持转换多组数据。其中data是一维的list
    # filename  输出的文件名
    write_VESTA_format(potential["AtomInfo"], [potential["Potential"]["TotalElectrostaticPotential"], potential["Potential"]], "DS-PAW.vesta")

.. admonition:: 知识点：

    1. `使用 with open语法 加载需要处理的三维网格数据；`
    2. `使用 write_VESTA_format函数 可以将三维数据保存为VESTA格式的数据，其中 potential["AtomInfo"] 为晶格信息， potential["Potential"]["TotalElectrostaticPotential"] 总的静电势的数据，之后将数据命名为 DS-PAW.vesta ；`
    3. `write_VESTA_format 支持输出多个网格数据，例如想要保存总的和自旋静电势，命令如下：write_VESTA_format(potential["AtomInfo"], [potential["Potential"]["TotalElectrostaticPotential"], potential["Potential"]["SpinElectrostaticPotential"]], " DS-PAW.vesta ")`

**注意：电荷密度和elf的三维数据处理与势函数的一致，都可以使用函数write_VESTA_format。**

执行代码可以得到VESTA支持的数据，将数据拽入VESTA中得到以下势函数三维图：

.. figure:: images/4-12.png

（2） **将三维势函数进行面内平均：**

创建 :guilabel:`plot _planar_macroscopic.py` 文件，具体代码如下：

.. code-block:: python

    import json
    import numpy as np

    # 导入绘制沿某个方向求平均的potential图片模块
    from dspawpy.plot import plot_potential_along_axis
    # 读取potential.json
    with open("./data/potential.json","r") as file:
        potential = json.load(file)

    # 获取grid
    grid = potential["AtomInfo"]["Grid"]
    # reshape,数据按照列优先的原则处理
    pot= np.asarray(potential ["Potential"]["TotalElectrostaticPotential"]).reshape(grid,order="F")

    # 画图，参数 np.ndarray[:,:,:],3维数组
    # axis:(0,1,2),方向
    plt = plot_potential_along_axis(pot,axis=2)
    plt.legend()
    plt.show()

.. admonition:: 知识点：

    1. `进行面内平均及宏观平均时需要使用到 numpy 的库；`
    2. `DS-PAW软件中三维的数据都是按照一维的格式保存的，因此需要使用 np.asarray函数 将一维数据还原成3维数据；`
    3. `之后使用 plot_potential_along_axis 将某两个维度进行求平均，之后将剩下的维度数据进行绘图；`
    4. `plot_potential_along_axis的第一个变量为三维格点数据，第二个为沿着某个维度画图，将另外两个维度求平均，第三个参数为是否绘制宏观平均的曲线，第四个参数为宏观平均算法中的权重；`
    5. `此案例中设置参数为： pot , axis=2 ；`

**注意：电荷密度和elf也可以使用相同的处理方式处理。**

执行代码可以得到以下势函数图：

.. figure:: images/4-13.png